Skip to content

shopify_api 1.0: release candidate 1.0.0-rc.1 is out, feedback wanted - #33

Merged
0xtlt merged 135 commits into
masterfrom
RC-1.0.0
Oct 27, 2026
Merged

0xtlt merged 135 commits into
masterfrom
RC-1.0.0

Conversation

@0xtlt

@0xtlt 0xtlt commented Oct 26, 2026 •

Copy link
Copy Markdown
Owner

1.0.0-rc.1 is on crates.io. 1.0 is a rewrite. Your GraphQL operations are checked against Shopify's Admin schema while your crate compiles, and their variables and results become Rust types. Around them, the client handles tokens, throttling, bulk operations, webhooks and OAuth.

The release candidate is opt-in: cargo add shopify_api still installs 0.10.1. I'm waiting for your feedback before tagging 1.0.0. After that tag, a breaking change has to wait for a 2.0. This PR stays open until then. What I'd like to hear about is under Feedback wanted, below.

[dependencies]
shopify_api = "=1.0.0-rc.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

In 30 seconds

use shopify_api::{Auth, Shopify, graphql};

let shopify = Shopify::new("my-shop", Auth::access_token("shpat_…"))?;

let data = shopify
    .execute(graphql!(
        "query($first: Int!) { products(first: $first) { nodes { id title totalInventory onlineStoreUrl } } }",
        first = 10,
    ))
    .await?;

for product in data.products.nodes {
    // `total_inventory`: i64. `online_store_url`: Option<String>, nullable in the schema.
    println!("{}: {} in stock, {:?}", product.title, product.total_inventory, product.online_store_url);
}

A typo does not reach Shopify. It fails the build:

error: Type `Product` has no field `titel` (did you mean `title`?) (line 1, column 60)
       (checked against the Shopify Admin API 2026-10)

There is no build script, no generated file and no codegen step. The macro reads one schema file next to your Cargo.toml.

The client runs on Tokio: the default transport and the token renewals need a Tokio runtime.

What's in 1.0

  1. Operations checked at compile time
  2. Variables and input objects, written as literals
  3. Named operations and .graphql files
  4. Typed bulk operations
  5. Schema and API versions
  6. Tokens
  7. Throttling and retries
  8. Webhooks
  9. OAuth and embedded apps
  10. Pagination, untyped calls, tests, errors

1. Operations checked at compile time

graphql! parses the operation and checks it against the schema:

  • Unknown names fail the build, with a suggestion when a name is close. This covers fields, arguments, enum values, directives and variables.
  • Deprecated fields and values are compiler warnings, with Shopify's reason.

The result is a struct generated from the selection, with snake-case fields:

GraphQL Rust
String, ID String
Int, Float, Boolean i64, f64, bool
JSON serde_json::Value
T without ! Option<T>
[T] Vec<T>
Object, interface, union A struct
Enum, and Shopify's other scalars (DateTime, Money, Decimal…) String, as Shopify sends it

Enum results are strings so that a value Shopify adds later doesn't break reading an answer. Enum values you write in the operation (sortKey: CREATED_AT) are checked.

2. Variables and input objects, written as literals

Variables follow the operation as name = value, and each value is converted to the variable's type:

  • any integer type for an Int;
  • &str or String for an ID;
  • a slice or a Vec for a list;
  • a bare value or an Option for a nullable variable.

A value of the wrong type fails the build at that value.

Input objects are object literals, checked field by field:

shopify.execute(graphql!(
    "mutation($product: ProductUpdateInput!) {
       productUpdate(product: $product) { userErrors { field message } }
     }",
    product = {
        id: product_id,                     // any Rust expression
        title: format!("{name} (promo)"),
        status: ACTIVE,                     // an enum value, checked
        descriptionHtml: null,              // sends null: Shopify clears it
        vendor?: new_vendor,                // an Option: None leaves the field out
        seo: { title: seo_title },          // a nested input object
        metafields: [for m in rows if !m.value.is_empty() => {
            namespace: "custom", key: &m.key, value: &m.value, type: "single_line_text_field",
        }],
    },
)).await?;

There are four ways to write a field:

You write Shopify gets
title: value the value
title: null null: Shopify clears the field
title?: option the value for Some; for None, nothing, and Shopify keeps what it has
title?: maybe a shopify_api::Maybe: Value, Null, or nothing for Absent

title: option does not compile. Sending null for a None would silently clear the field on Shopify's side. The compiler points to the two explicit spellings:

error[E0277]: `vendor` of `ProductUpdateInput` expects a `String`, not `Option<String>`
   = note: `vendor?: value` takes an `Option`, `None` leaving the field out; `vendor: null` sends `null`

These are also compile errors, each pointing at the token:

  • an unknown or repeated field;
  • a missing required field;
  • null on a non-null field;
  • an unknown enum value;
  • an @oneOf input with other than exactly one field.

For example:

error: `ACTIV` is not a value of the enum `ProductStatus` (did you mean `ACTIVE`?):
       `status` of `ProductUpdateInput` takes `ACTIVE`, `ARCHIVED`, `DRAFT` or `UNLISTED`

For an enum value known only at run time, raw(value) sends the string unchecked.

input! builds an input object ahead of the call, in a loop for instance. Every input! of one GraphQL type has the same Rust type, so values built in different places go in one Vec:

use shopify_api::input;

let mut metafields = Vec::new();
for row in rows {
    if row.color.is_empty() { continue; }
    metafields.push(input!(MetafieldsSetInput {
        ownerId: &row.product_id, namespace: "custom", key: "color", value: &row.color,
        type: "single_line_text_field", compareDigest?: row.digest.as_deref(),
    }));
}
shopify.execute(graphql!(
    "mutation($metafields: [MetafieldsSetInput!]!) {
       metafieldsSet(metafields: $metafields) { userErrors { field message } }
     }",
    metafields = metafields,
)).await?;

Values Shopify would not read as written are refused before anything is sent. In 0.10, a NaN went out as null and cleared the field. Now:

  • a Float must be finite;
  • an Int must fit in 32 bits;
  • a non-null JSON must not be null.

An out-of-range integer literal fails the build. A value known only at run time fails the call with Error::InvalidValue, which names the place and never the value: invalid value at `$product.metafields[2].value`: not a finite Float.

3. Named operations and .graphql files

graphql! { pub mod name = "…"; } names the generated types, so functions can take and return them. One block holds several modules. A module's Variables runs as it is, and the module names each input type it uses:

graphql! {
    pub mod metafields_set = "mutation MetafieldsSet($metafields: [MetafieldsSetInput!]!) {
        metafieldsSet(metafields: $metafields) { metafields { id key } userErrors { field message code } }
    }";
    pub mod shop_name = "query ShopName { shop { name } }";
}

fn color_metafields(rows: &[Row]) -> Vec<metafields_set::MetafieldsSetInput> {
    rows.iter()
        .map(|row| input!(MetafieldsSetInput {
            ownerId: &row.product_id, namespace: "custom", key: "color", value: &row.color,
            type: "single_line_text_field",
        }))
        .collect()
}

let data = shopify.execute(metafields_set::Variables { metafields: color_metafields(&rows) }).await?;
let shop = shopify.execute(shop_name::operation()).await?;

pub mod order = file("graphql/order.graphql"); reads the operation from a file. shopify-api check graphql/*.graphql checks those files the same way, in CI or for other tools that use them.

4. Typed bulk operations

graphql!(bulk("…")) checks a bulk query against Shopify's bulk rules as well as the schema:

  • one top-level connection;
  • at most five connections, at most two levels deep;
  • edges { node } only;
  • no first, last, after or before;
  • an unaliased id on each node that has nested connections.

A bulk query that Shopify would reject, or silently read differently, fails the build:

error: Shopify ignores `first` in a bulk query and returns every object of `products`: remove it (line 1, column 3)
       (checked against the Shopify Admin API 2026-10)

The results are generated types too. Each nested connection is a Vec of its nodes, put back under its parent as the file downloads. Memory holds one top-level object at a time, not the whole export:

use shopify_api::bulk::BulkWaitOptions;

graphql! {
    mod catalog = bulk("query($filter: String) {
        products(query: $filter) { edges { node {
            id title
            variants { edges { node { sku price } } }
        } } }
    }");
}

let mut products = shopify
    .bulk_query(catalog::Variables { filter: Some("status:active".into()) }, BulkWaitOptions::default())
    .await?;

while let Some(product) = products.next_item().await {
    let product = product?; // catalog::Item
    println!("{}: {} variants", product.title, product.variants.len());
}

Shopify takes no variables for a bulk query. The crate writes them into the query text as GraphQL literals, typed and escaped.

A bulk mutation runs over an iterator of its Variables. Every line is checked before anything is uploaded, and each result line is typed:

graphql! {
    pub mod tag = bulk("mutation($id: ID!, $tags: [String!]!) {
        tagsAdd(id: $id, tags: $tags) { userErrors { field message } }
    }");
}

let lines = ids.iter().map(|id| tag::Variables { id: id.clone(), tags: vec!["sale".into()] });
let mut results = shopify.bulk_mutation(lines, BulkWaitOptions::default()).await?;

while let Some(result) = results.next_row().await {
    let result = result?;
    if let Some(payload) = result.data.and_then(|data| data.tags_add) {
        for error in payload.user_errors {
            println!("line {:?}: {}", result.index, error.message);
        }
    }
}

Untyped bulk methods run any text, such as a query built at run time:

Method What it does
bulk_query_rows Runs the query and collects every line into a Vec
bulk_query_stream Streams lines as the file downloads (exports of gigabytes)
bulk_query_grouped Streams each object with its children
start_bulk_* Only starts an operation
wait_for_bulk_operation, cancel_bulk_operation, download_bulk_* The other steps, one by one

5. Schema and API versions

No schema ships with the crate:

  1. The first build downloads the schema of the latest stable version into graphql/admin.schema.json. Commit it.
  2. Later builds keep that version, whatever Shopify releases in the meantime. A build gives the same result whatever the date.
  3. Each operation is sent to the version it was checked against, so the version used for checking and the version used for sending stay the same. The exception is a client you pin to one version with Shopify::builder(…).api_version(…): every request then goes to that version.

To choose the version, pin it:

[package.metadata.shopify_api]
api-version = "2026-07"
schema = "schemas/admin-2026-07.json"   # optional: another file, inside the package

The schema belongs to each crate. A library that uses graphql! ships its own file, and a dependency never downloads or writes one. If a library forgets the file, cargo package fails before it is published.

The shopify-api command (cargo install shopify_api --features cli) has two jobs:

  • shopify-api schema download refreshes the file. --shop downloads the schema your token sees, and --only cuts the file down to the operations you use.
  • shopify-api check validates .graphql files.

6. Tokens

// A custom app's token, or an offline token stored at install.
let shopify = Shopify::new("my-shop", Auth::access_token("shpat_…"))?;

// Client credentials: 24-hour tokens, asked for and renewed by the client.
let shopify = Shopify::new("my-shop", Auth::client_credentials(client_id, client_secret))?;

// An expiring offline token, renewed with its refresh token and saved.
let shopify = Shopify::builder("my-shop")
    .auth(Auth::expiring_token(client_id, client_secret, stored_token))
    .token_store(MyDatabase)
    .build()?;

The client handles the renewals:

  • When: shortly before a token expires, and once more if Shopify refuses it with a 401.
  • Shared: clones of a client share one token. One renewal serves every clone and every request waiting for it.
  • Not cancelled by callers: a renewal runs in its own task, so a request that gives up can't lose a rotated refresh token.
  • Saved before anything is sent: after a renewal, nothing goes out until your TokenStore has saved the new token. A failed save is tried again on the next call, which fails with Error::TokenStore until it succeeds.

7. Throttling and retries

Retries are on by default, four of them:

  • A throttled request, query or mutation, did not run. It waits until the bucket holds its cost again (computed from extensions.cost, up to max_delay, 30 s by default), then goes again.
  • A 429 waits for its Retry-After, up to max_retry_after (five minutes by default). A longer wait ends in Error::Throttled { retry_after, … }.
  • A query is retried after a 5xx or a network failure, with exponential backoff and jitter.
  • A mutation is not retried after a 5xx or a network failure, since it may have run.
use shopify_api::RetryPolicy;
use std::time::Duration;

let shopify = Shopify::builder("my-shop")
    .access_token(token)
    .retry(RetryPolicy::new(6).with_max_delay(Duration::from_secs(10)))
    .build()?;

let response = shopify.execute_response(graphql!("query { shop { name } }")).await?;
println!("{:?}", response.cost()); // requested and actual cost, what is left

RetryPolicy::none() gives 0.10's behaviour: fail at the first throttle.

8. Webhooks

Feature webhooks:

use shopify_api::webhooks::{Webhook, WebhookSubscriptionSpec};

// In your handler, on the raw body. `headers`: an `&http::HeaderMap`, or an iterator of (name, value) pairs.
let webhook = Webhook::verify(&headers, body, client_secret)?;
match webhook.topic() {
    "orders/create" => {
        let order: MyOrder = webhook.payload()?;
    }
    "app/uninstalled" | "shop/redact" | "customers/redact" => {
        // The signature covers the body, not the headers: check the payload names the same shop.
        webhook.verify_payload_shop()?;
    }
    _ => {}
}

// Make the shop's subscriptions exactly these: updated in place, created before anything is deleted.
shopify.sync_webhook_subscriptions(&[
    WebhookSubscriptionSpec::new("orders/create", "https://example.com/webhooks"),
    WebhookSubscriptionSpec::new("app/uninstalled", "https://example.com/webhooks"),
]).await?;

Webhook::verify does four things:

  • reads the headers in any case, with or without the X- prefix;
  • accepts several secrets during a rotation, with Webhook::verify_with_secrets;
  • gives event_id(), so you can drop a duplicate delivery;
  • verifies JSON webhooks only, refusing a body whose first byte isn't {. The client secret also signs other strings (launch queries, app proxy requests, session tokens), and none of them may pass for a webhook.

When sync_webhook_subscriptions keeps an XML subscription (same topic and address), it updates it to JSON.

9. OAuth and embedded apps

Feature oauth:

use shopify_api::oauth::{RequestedToken, ShopifyApp};

let app = ShopifyApp::new(client_id, client_secret).with_token_store(MyDatabase);

// Embedded app: verify the session token of the request, exchange it for an access token.
let session = app.verify_session_token(bearer)?;
let token = app.exchange_session_token(&session, RequestedToken::ExpiringOffline).await?;
let shopify = app.client(session.shop(), token)?;

// Checkout and customer account UI extensions: a type of their own.
let extension = app.verify_extension_session_token(bearer)?;
let customer = extension.customer(); // Some("gid://shopify/Customer/…") when logged in

ShopifyApp covers the whole app flow:

  • the install link and the callback (authorization_url, verify_query, exchange_code);
  • admin launches;
  • app proxy requests (verify_app_proxy);
  • the token exchange.

Admin session tokens and extension session tokens are signed with the same secret, but any buyer of the shop can get an extension token. So they verify into two distinct types:

  • verify_session_token takes only admin tokens, and the result can be exchanged for an access token;
  • verify_extension_session_token returns an ExtensionSessionToken, which can't be exchanged. A buyer's token never passes for an admin session.

10. Pagination, untyped calls, tests, errors

Pagination:

use shopify_api::Page;

let products = shopify
    .paginate(
        |after| graphql!(
            "query($after: String) {
               products(first: 250, after: $after) { nodes { id title } pageInfo { hasNextPage endCursor } }
             }",
            after = after,
        ),
        |data| Page::new(data.products.nodes, data.products.page_info.has_next_page, data.products.page_info.end_cursor),
    )
    .await?;

Untyped calls, for operations built at run time:

  • shopify.graphql(query, variables) returns data as a serde_json::Value;
  • graphql_as::<T> reads it as your type;
  • graphql_raw returns the whole answer, errors included.

Tests without the network: feature testing gives a MockTransport, which records what the client sends and answers what the test says:

use shopify_api::testing::{MockTransport, client};

let mock = MockTransport::new();
mock.push_data(serde_json::json!({ "shop": { "name": "Test shop" } }));
let shopify = client(&mock);

// `shop_title` is your code: it runs `query Shop { shop { name } }`.
assert_eq!(shop_title(&shopify).await?, "Test shop");
assert_eq!(mock.graphql_requests()[0].operation_name.as_deref(), Some("Shop"));

Errors that keep data out of your logs. An Error never shows a response body, a value or map key from an answer, a value of your variables, a query string, or serde's messages. Shopify's own errors and userErrors messages are shown as Shopify wrote them (one may quote part of an invalid variable), and so are the errors of your Transport and TokenStore:

  • Error::Http shows the status, the address and the length of the body, and carries Shopify's X-Request-Id;
  • Error::Decode shows the kind of mismatch and the path of the field;
  • raw_http_body() and sensitive_detail() give the rest when you need it.

Features:

Feature
rustls (default) The default HTTP transport, over rustls
native-tls The same, over the platform's TLS
webhooks Webhook verification and subscriptions
oauth Install links, callbacks, token exchange, session tokens, app proxies
testing MockTransport and the signing helpers for tests
cli The shopify-api command
full Everything but native-tls

Without rustls or native-tls, plug in your own Transport.

Upgrading from 0.10

1.0 needs Rust 1.88 or newer. Most code changes in three places:

  1. building the client;
  2. the error type;
  3. GraphQL calls.
The main renames
0.10 1.0
Shopify::new(shop, ShopifyAuth::AccessToken(t), ShopifyConfig::default()) Shopify::new(shop, Auth::access_token(t))
ShopifyConfig { api_version, token_store, … } Shopify::builder(shop).api_version(…).token_store(…)
ShopifyAPIError Error
shopify.graphql::<T>(…) shopify.graphql_as::<T>(…), or graphql!
post_graphql (feature graphql-client) graphql!
run_bulk_query(q) (which only started it) start_bulk_query(q), or bulk_query_rows for the whole cycle
TokenStore::save_token(&str, TokenData) TokenStore::save(&ShopDomain, &TokenData)
replace_auth Build a new client
Default API version 2026-04 The version of your schema for graphql!, 2026-10 for untyped calls

These changes need attention:

  • Webhooks verify JSON only. Move XML subscriptions to JSON before you deploy 1.0. MIGRATION.md gives the order.
  • Retries are on by default. 0.10 failed at the first throttle. RetryPolicy::none() keeps that behaviour.
  • Some things are gone with no replacement in the crate:
    • the typed webhook payload structs and the warp wrapper (a handler is a few lines, see MIGRATION.md);
    • run_bulk_queries and run_bulk_mutations, the concurrent bulk helpers;
    • utils.
  • The shop must be <name> or <name>.myshopify.com. 0.10 accepted any text.

Feedback wanted

Comment on this PR, or open an issue. Please include:

  • the api-version you use;
  • the code;
  • the full compiler message.

I'd most like to hear about:

  1. graphql! in your code:
    • Did a compile error confuse you, or point at the wrong place?
    • How much does the macro add to your build time?
  2. Typed bulk on a real store: large exports, nested connections, and bulk mutations.
  3. Multi-tenant apps:
    • Are Auth and TokenStore enough?
    • Or do you need to plug in your own token source, such as tokens loaded from a database per shop?
  4. Something you used in 0.10 and can't find, or can't do anymore.
  5. Names and shapes of the API. This is the last moment to change them without a 2.0.

Ideas for after 1.0. They are additive, so they don't block the release. Tell me which ones you need:

  • Your own token source, for tokens kept per shop in a database.
  • Re-exporting graphql! from another crate. The generated code refers to ::shopify_api today, so the dependency can't be renamed or re-exported.
  • Typed scalars and enums in results (DateTime, Money, Decimal…), which are Strings today.
  • A shared rate limiter across clients, instead of reacting to throttles.
  • The Storefront API.
  • Smaller additions:
    • an input object from JSON that keeps the checked version;
    • --api-version for shopify-api schema download;
    • a progress callback while a bulk operation runs;
    • access to response headers.

Status

  • 1.0.0-rc.1 published: shopify_api, shopify_api_macros, and shopify_api_graphql, which is internal with no semver guarantee.
  • CI green on every job:
    • fmt, clippy, tests and docs;
    • no default features, then webhooks, oauth and testing each alone;
    • Rust 1.88;
    • cargo package;
    • cargo deny;
    • the schema path rules on Windows.
  • The tests script Shopify with MockTransport: none of them reaches the network.
  • Several rounds of review, closed with no open finding.
  • Live tests on a development store (mise run test:live). The typed bulk reader relies on two behaviours of Shopify that its guide doesn't show:
    • the _shopifyApiTypename alias is kept in the JSONL file;
    • groupObjects writes each object right after its parent, at the second level too.
  • The admin HMAC of a query string with a repeated parameter (the ids[] of bulk-action links). It follows Shopify's JS library, but hasn't been checked on a real link.
  • Your feedback.
  • 1.0.0: set the version, date the changelog, merge, tag v1.0.0. The tag publishes the three crates.
For reviewers

🤖 Generated with Claude Code

0xtlt and others added 30 commits October 22, 2026 08:59
…t compile time

A rewrite around a `graphql!` macro that checks each query or mutation
against the bundled Admin schema (2026-10) and generates the types of its
variables and result. See MIGRATION.md for the move from 0.10.

- Workspace of three crates released together: shopify_api,
  shopify_api_macros and shopify_api_graphql (schema, analyzer, codegen).
- Deprecated fields, arguments, input fields and enum values are compiler
  warnings with Shopify's reason; directives come from the schema.
- Operations go to the version of the schema they were checked against;
  `shopify-api schema download` stores another version, `check` validates
  .graphql files.
- Tokens: static, client credentials, expiring with refresh; renewed in a
  task of its own, once for all clones, saved through a TokenStore.
- Retries: throttling waits for its cost, 429 for Retry-After, queries
  after 5xx or network failures, never a mutation.
- Pagination, bulk operations, webhooks (verification, subscription sync),
  OAuth and session tokens, MockTransport for tests.
- Errors never hold secrets or signed query strings.
- mise.toml for the toolchain and tasks; CI runs `mise run check`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Select the Admin API version with `api-version` in `[package.metadata.shopify_api]`; `graphql!` downloads its schema to `graphql/admin.schema.json` on the next build when it is missing or another version
- `shopify-api schema download` reads the version from Cargo.toml and no longer takes `--api-version`
- Rename the bundled schema file to `admin.schema.json`
- Add `shopify_api_graphql::project` (version lookup, schema source, atomic file writes), behind a `download` feature
- Add `toml` and `ureq` dependencies
- No schema ships with the crates. `graphql!` downloads the schema of the crate's API version on first build and again when the version changes.
- Default version is the latest stable one. `api-version` in `[package.metadata.shopify_api]` pins it.
- `shopify-api schema download --only <files>` keeps only the types and fields those `.graphql` files use.
- Crate operations are checked against a trimmed `graphql/internal.schema.json`, and the Admin schema moves to `crates/shopify_api/graphql/`.
- Add `.cargo/config.toml` pointing `SHOPIFY_GRAPHQL_SCHEMA` at the test schema.
`--cfg docsrs` turns on `feature(doc_cfg)`, which stable Rust rejects, so
the `doc` task failed in CI. docs.rs still sets the flag itself, on nightly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…work

Pinning a version that is not out yet, or misspelt, failed with "build once
with network access and commit the file", though the download had worked:
Shopify answers such a version with a 400 "Invalid API version".

- The downloads of `shopify_api_graphql::project` return a `DownloadError`,
  whose `UnknownVersion` is that answer.
- `graphql!` then names the version and suggests a released one. Other
  failures keep the advice to build with network access.
- When the latest version is not out and the one before fails too, the
  error is the one before's, the one to fix.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both v4/v2 ran on the deprecated Node 20 runtime.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
OperationKind::of ended comments at \n only, so "# c\rmutation { … }" read
as a query and was sent again after a 5xx or a network failure. It now
lexes the document: comments end at \r, \n or \r\n (the spec's
LineTerminator), strings and block strings are skipped, and a document it
cannot read to the end (subscription, typo, unbalanced braces) counts as a
mutation, so it is never retried.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A 429's Retry-After was clamped to max_delay (30 s by default), so a
120-300 s cooldown burned every retry early. max_delay now caps only the
computed backoff. A Retry-After longer than the new
RetryPolicy::max_retry_after (5 min by default) is not waited for: the
request ends in Error::Throttled, which now carries that wait in
retry_after (the variant is #[non_exhaustive], so this is additive).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
timestamp=-9223372036854775808 overflowed `now - timestamp` in
verify_query and verify_app_proxy before the signature was checked.
The distance is now an abs_diff, and the timestamp is only read once
the HMAC (constant-time verify_slice) holds. Session token exp/nbf
checks use saturating arithmetic for the same reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- testing::GraphqlRequest: manual Debug, access_token shown as [redacted].
- transport::HttpRequest: the URL is shown without its query string, so a
  signed bulk-download address no longer leaks its signature.
- transport::HttpResponse: secret headers (now also Set-Cookie and
  Proxy-Authorization) redacted; a Location header loses its query string.
- bulk::BulkOperation: url and partial_data_url shown without their
  query string.
- CLI DownloadArgs: access token and client secret redacted.

The fields themselves are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
auth.rs spawns the token renewal with tokio::spawn, which needs tokio's
`rt` feature; only `sync` and `time` were declared, so
`cargo check -p shopify_api --no-default-features --lib` failed with
E0425 while reqwest's tokio features hid it in the default build. The
crate now declares `rt`. A new `check:features` mise task builds the
library with no default features and with each feature alone; CI runs
it in its own `features` job, required by "CI is green".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
restricted_to dropped the possible types of interfaces and unions that
no operation selected, so in a cut schema `node { ... on Product { title } }`
made Product the only Node: the fragment always applied and `title`
became `String` instead of `Option<String>`. Decoding an Order then
failed with "missing field title". Interfaces and unions now keep their
whole list of possible types (the names only; the types stay out).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ypes

The analyzer required every selection of a response key to be the same
field with the same arguments, so
`node { ... on Product { label: title } ... on Order { label: name } }`
was refused. Per the spec's FieldsInSetCanMerge, when the two parents are
different object types (never both present), only the shape of the
answer must agree; the field names and arguments may differ. On the same
type or an interface they still must match. The shape check stays
strict: the two types must be the same (same nullability, lists and
named type), so the merged key keeps a single Rust type.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A response that returns a bulk operation's signed url next to an errored
field ended in Error::Graphql, whose derived Debug printed the url.
Debug now lists the keys of the partial data, not their values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ry-After

Since Retry-After is honored past max_delay, a mocked 429 with
Retry-After: 300 made the test client sleep five minutes. An internal
RetryPolicy flag, set only by testing::client, retries at once; a wait
beyond max_retry_after still ends in Error::Throttled. Production
clients are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RFC 9110 allows Retry-After as an HTTP date. Only seconds were read, so
a dated 429 was retried after the 1s backoff. The three HTTP-date forms
are now parsed with chrono (already a dependency), the wait is counted
from now, a past date is no wait, and max_retry_after applies as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The spec (All Variable Usages Are Allowed) lets a nullable variable fill a
non-null location only with a non-null default. `$id: ID = null` was
taken as a default and passed. A "gid://..." default is still accepted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql-parser keeps input objects in a map, so in
{id: "1", title: "old", title: "new"} the first title vanished before
validation while the text sent to Shopify kept both. A small scan of
the text applies Input Object Field Uniqueness before analysis.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`... on ProductVariant { x: image { a: url } } ... on Collection { x: image
{ a: originalSrc } }` was refused: the subselections of `x` merged on Image
and lost the fact that their parents can never both be present. Each
place now carries the parent types above it; two places whose chains
differ by two object types at some depth only need the same shape
(FieldsInSetCanMerge / SameResponseShape). Same type or an interface
still needs the same field and arguments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GraphQL Ruby answers a variable that does not validate with its whole
value under extensions.value, so a signed originalSource reached logs
through {:?} of Error::Graphql. GraphqlError's Debug now shows the
message, locations, path, extensions.code and only the names of the
other extensions. errors that are neither a list nor a string keep
their value in extensions.value instead of the message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Error documented that secrets never appear in it; decode and HTTP errors
did not hold to it.

- Error::Decode (and the token endpoint and variables errors) keep the
  path and the kinds of value, not the values serde quotes:
  'invalid type: string "…"' becomes 'invalid type: string'.
- Error::Http shows at most 1 KiB of the body, with address query
  strings, token-like words (shp…_ prefixes, JWTs, long mixed
  letters and digits) and the values of secret-named entries replaced
  by [redacted], in Display and Debug. The whole body stays available
  through Error::raw_http_body and the new raw_body: RawBody field,
  whose Debug shows its length only.
- The doc of Error states what is guaranteed and what is shown as is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
chrono's %y pivots at a fixed year, so in 2069 a Retry-After of
'Wednesday, 06-Nov-69 …' did not parse, and later two-digit years
would be read a century off. The century is now chosen from the
current date: the latest year with those two digits that is not more
than 50 years ahead (RFC 9110 §5.6.7). The weekday must still match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The duplicate input field scan searched a Vec of the fields given so
far, quadratic in the size of one object: 100,000 fields took about
50 s in a debug build, 0.2 s with a HashSet per object. Same results.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Arguments were compared as text, and graphql-parser writes 1.0 as 1
and keeps input objects in a map, so x: f(a: 1) and x: f(a: 1.0), or
{a: 1, b: 2} and {b: 2, a: 1}, were merged while Shopify's GraphQL
Ruby refuses both with fieldConflict.

Values are now compared structurally, by kind (Int, Float, String,
Enum, Boolean, null, variable, list, object): -0.0 is not 0.0, 1.0 is
1.00, a block string is the string it holds. The order of an input
object's fields, which the parser drops, is read back from the text at
the position the parser gives; when it cannot be, the selection is
refused rather than sent. Messages write each value with its kind.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A key selected on two exclusive object types had to name fields of the
same type, so nodes { ... on Product { price: priceRangeV2 { … } }
... on Order { price: totalPriceSet { … } } } was refused although its
answers have one shape. Two places of a key now need the same lists,
nullability and scalar or enum, or two types with subfields; the
subfields of every place are merged, each collected on the type of its
own place, and checked the same way at every depth. Where both places
can be in one answer the field and its arguments must still match.

The merged selection becomes one struct whose fields are those of
every place, optional unless every place selects them; Selection::types
lists the types it is selected on.

Also refuse a field of an object type that has subfields at one place
and none at another ({ shop { name } shop } was accepted).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
is_word keeps '=' and '/' in a word, so 'x=shpat_…' or '/eyJ…' were one
word that did not start like a token. Shopify token prefixes and JWTs
are now found after any non-alphanumeric character of a word.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…input

Text scrubbing kept missing secrets (escaped quotes, JSON \u escapes,
tabs, escaped slashes, map keys, bulk counts, variables errors). Errors
now never put text they did not write in Display, Debug or source():

- Error::Http shows the status, address, content type and body length;
  the body stays in raw_http_body(). The redacted `body` preview is gone.
- Error::Decode: a new path-tracking deserializer (decode.rs) names only
  the fields and variants the Rust type declares (&'static str), writes
  `[key]` for map keys, and describes the mismatch in its own words with
  the line and column. serde's message is in sensitive_detail().
- Error::Variables: one path for Operation::variables, json_variable and
  graphql_raw; the Serialize message is in sensitive_detail().
- Error::Auth: the token endpoint's status and a known OAuth code; its
  answer is in sensitive_detail().
- Bulk counts, ids, statuses and error codes are not echoed.
- InvalidShop/InvalidApiVersion do not show the text given; addresses
  lose their user and password too; GraphQL data/extensions Debug counts
  entries instead of naming them.
- Error::Json and From<serde_json::Error> are gone; redact.rs,
  serde_path_to_error and thiserror are dropped.

A test builds every variant from secret-bearing input and checks
Display, Debug, {:#?} and the source chain.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`draftOrderCreate: draftOrderCreate(...)` skipped the argument scan: the
alias was detected by `alias != name`, so the colon stayed unread and the
scan returned no arguments, and input objects in different orders
compiled although GraphQL Ruby refuses them (fieldConflict). The colon
token now says whether there is an alias.

The analyzer docs say where it is stricter than the specification, and
why.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`Tuesday, 29-Feb-00 08:49:37 GMT` read as 2100-02-29 first, which does
not exist, and the parse gave up before trying 2000: a past Retry-After
fell back to the ordinary backoff instead of no wait. The day, month and
time are now read in a leap year, the century is chosen, then the date
is built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
0xtlt and others added 22 commits October 26, 2026 12:14
A "Bulk operations" section in the documentation of `graphql!`: the rules
checked, the items and their connections, the variables written into the
text, bulk mutations, and what is not checked. The module docs of `bulk`,
the README, the CHANGELOG and MIGRATION show the typed path first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A bulk query writes an enum variable bare. A `String` or `raw("…")`
holding `null`, `true` or `false` passed the name check and was sent as
`null` or a boolean: another value than the one given. They now fail
with `InvalidValueReason::ReservedEnumValue` before anything is sent; a
real `null` is still written `null`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A bulk query is sent as text written back from what `graphql-parser`
read, and 0.4.1, its latest release, reads `\b` as U+0010 and splits
and indents block strings unlike the specification (a lone `\r`,
Unicode whitespace). Its values carry no position and input objects are
sorted maps, so the original tokens cannot be mapped back reliably.

Each string token of a bulk query is now decoded as the specification
does and compared with what the parser read; a difference is a compile
error that says what to write instead (`\u0008` for `\b`, a quoted
string for a block string).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A line's `id` places its children only when it is a string: another
  value, such as `id: totalInventory`, no longer fails every line with
  `Error::Decode`. On a node with nested connections, which must select
  `id` itself, another field aliased `id` is refused at compile time.
- Where lines need it, the text sent selects
  `_shopifyApiTypename: __typename` and lines are routed by that key
  alone: a `__typename` of the query, aliased or conditional, is left as
  written instead of merging with an unconditional one. The alias is
  reserved and refused in a bulk query.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UI tests for a `\b` string, the `_shopifyApiTypename` alias and an `id`
alias beside a nested connection. A constant named like a binding of the
generated code (`__shopify_api_parent`, `__shopify_api_value0`) fails to
compile with E0308: no binding form escapes a constant in scope (`ref`,
`mut` and `x @ _` all give E0530), so the prefix is documented as
reserved and the error pinned, for bulk and literal code alike.

The new files shift trybuild's crate indexes, which the hashed names of
five `literal_*` snapshots follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enum values `true`, `false` and `null` in a variable, a list and an
input field; every GraphQL escape and block strings, in constants and
defaults, decoded by the test's own decoder against the value written;
a string variable of every code point; `id` aliases of other types on an
item and a child; routing by `_shopifyApiTypename` beside a conditional
`__typename`. The changelog says what changed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql-parser 0.4 measures the common indentation of a block string in
bytes over any Unicode whitespace, then cuts each line at that byte: a
line indented with U+00A0 (two bytes) beside one indented with U+2003
(three bytes) made `graphql!` panic, bulk or not. Every parse now goes
through `analyze::parse`, which first runs the parser's own indentation
steps on each block string of the source and refuses one whose cut
falls inside a character, at its line and column.

The string lexer of the bulk checks moves to `source`, shared. A test
compares the check with the parser's panics over a grid of whitespace
mixes; UI tests pin the refusal for an ordinary and a bulk operation.
The other UI outputs change because trybuild numbers its test crates in
file order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`_shopifyApiTypename: products` and `__x: products` were accepted: the
top-level field went straight to `Checker::connection`, without the
`check_key` every field of a node goes through. The docs and changelog
reserve these aliases in the whole bulk query, so the top-level field
is checked as well. Pinned by a unit test and a UI test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The variables section said a `None` is written `null`. A `None` in an
optional field of a module's `Variables` leaves the variable out: its
argument goes, or takes the variable's default. Only a `null` given as a
value (`sort = null`, an inline `Option` that is `None`, a `None` in a
list, `null` or `Maybe::Null` in an input object) is written `null`, and
it replaces the default. The docs and changelog say so; a test pins the
three cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…sport

Without `rustls` or `native-tls`, `build` has no transport and the
example failed with `NoTransport` under `--no-default-features`. Its
body now runs only with a transport feature, the text shown unchanged.
`check:features`, which CI's `features` job runs, now also runs the
doctests of `shopify_api` without default features.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ion)`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
verify_session_token takes only the tokens of Shopify admin again: dest
exactly https://{shop}.myshopify.com, iss exactly its /admin, compared
whole (a prefix let https://s.myshopify.com.evil.example/admin pass).
SessionToken::subject is user_id again.

verify_extension_session_token verifies the tokens of checkout and
customer account UI extensions, which any buyer gets, as an
ExtensionSessionToken (shop, customer, claims) that does not exchange
for a token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…alEq

So that a progress callback or a retry predicate can be added after 1.0
without a breaking change. They stay Clone, Debug and Default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…onnections

start_bulk_* only starts and returns the operation; bulk_query* and
bulk_mutation start, wait and read.

- start_bulk_query takes a text (&str, String), GroupObjects(text) for
  groupObjects, or a graphql!(bulk(…)) query or its Variables, through
  the sealed StartBulkQuery trait. run_bulk_query and
  run_bulk_query_grouped(query, bool) are gone.
- run_bulk_mutation and run_bulk_mutation_iter are
  start_bulk_mutation_text, over any iterator (a slice by reference);
  run_bulk_mutation_staged is start_bulk_mutation_staged.
- A typed bulk query asks for groupObjects only when its item has nested
  connections: Shopify documents grouping as slower and more likely to
  time out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tions

An ignored test, run by mise run test:live, for
products { variants { metafields } media { ... on MediaImage } }: its
items are compared with the raw JSONL regrouped by __parentId. It checks
that Shopify keeps the _shopifyApiTypename alias and the groupObjects
order at the second level. It creates a fixture product, tagged
shopify-api-live-test, when the store has none of that shape.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ackages only

The published macro honoured SHOPIFY_API_INTERNAL_TEST_SCHEMA for every
package, dependencies included. It now applies only when CARGO_PKG_NAME
is shopify_api or shopify_api-tests, the name trybuild gives its
projects; any other crate keeps its own schema. Pinned by a unit test
and by a probe workspace built with the variable set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ate only

One function names the crate path; every generated item goes through
::shopify_api::__private (Result, Operation, OperationKind, InputObject,
Maybe, bulk::BulkQuery, bulk::BulkMutation). The bulk codegen used
#krate::Result, which a crate re-exporting shopify_api with a Result of
its own shadowed. A probe app that depends only on a facade crate
(extern crate facade as shopify_api) with its own Result, Operation and
bulk now compiles. A future crate = … stays additive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…with 0.10

MIGRATION: what to do in order when subscribed in XML, verify_hmac marked
JSON only, WebhookSubscription non_exhaustive with new required fields,
wait_for_bulk_operation returns Ok with status Failed while the
start-wait-read calls fail with Error::Bulk, access_token() then token(),
the InvalidApiVersion and Timeout rows, ApiVersion::default() moving from
2026-04 to 2026-10. CHANGELOG: the matching Breaking bullets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…omer

`ExtensionSessionToken::customer` is the GID of a logged-in customer: the
`sub` of an admin token, a staff member, stays in `claims()`. And
`start_bulk_query` of anything else than a bulk query says so, rather
than asking for `From` (`#[diagnostic::do_not_recommend]`).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xtlt 0xtlt changed the title shopify_api 1.0.0: operations checked against Shopify's schema at compile time shopify_api 1.0: release candidate 1.0.0-rc.1 is out, feedback wanted Oct 26, 2026
0xtlt and others added 3 commits October 27, 2026 10:04
…the names

Shopify sorts the whole `name=value` strings of an app proxy request.
Sorting by name differs when one name extends another by a byte below
`=` (`page`/`page2`, `filter`/`filter.v.price.gte`), so a request
Shopify signed was refused. Admin queries keep sorting by name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A caller that tells a lasting refusal (4xx with an OAuth code) from a
passing one (5xx, 408, 429, no code) had to parse the message. Error::Auth
now has `status`, `oauth_code` (OAuthErrorCode) and `held` (the failure
of a renewal another request ran), with accessors, filled for client
credentials, refresh, code exchange, token exchange and the held copies.
The Display text is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
graphql! (inline, modules, bulk) and input! take `crate = path` first,
so a crate that uses them through a framework re-exporting shopify_api
needs no shopify_api in its own Cargo.toml. The default stays
::shopify_api. The path must be absolute; `$crate` is refused, since
serde's derive reads it as text. The schema and API version are still
those of the calling crate.

The trybuild crate names shift with the new UI case, which moves the
crate-name hash in five expected outputs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xtlt

0xtlt commented Oct 27, 2026

Copy link
Copy Markdown
Owner Author

Three fixes from the openshop port onto rc.1 (openshop-rust#36):

  1. fix(oauth) (a5d5b3d): app proxy signatures now sort the whole name=value strings, the way Shopify does, instead of sorting by name. Before this, a request Shopify really signed with page/page2 or filter/filter.v.price.gte was refused. Admin query HMACs are unchanged. The tests use signatures computed outside the crate.
  2. feat(auth) (ffcc861): Error::Auth gains status, oauth_code (OAuthErrorCode) and held, with the accessors token_endpoint_status(), oauth_code() and is_held_auth_failure(). They are set for client credentials, refresh, code exchange, token exchange and held failures, and are None when the error is not an HTTP refusal. The Display text is unchanged.
  3. feat(macros) (d511689): graphql! and input! accept crate = ::path::to::shopify_api (inline, modules, bulk, input!). The default is still ::shopify_api. The path must be absolute, and $crate is refused because serde's derive reads the path as text. A fixture app that depends only on a re-exporting crate builds and runs.

No version bump, tag or publish.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@0xtlt
0xtlt merged commit e69759c into master Oct 27, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant